#pragma once
#include <Arduino.h>

/**
 * @brief 蜂鸣器控制类
 * 
 * 提供蜂鸣器的基本控制功能，包括初始化、播放音调和停止
 * 使用ESP32的LEDC（PWM）功能控制蜂鸣器
 */
class Buzzer {
public:
  /**
   * @brief 构造函数
   */
  Buzzer();

  /**
   * @brief 初始化蜂鸣器
   * 
   * 配置PWM通道、频率和引脚
   * 默认频率为3000Hz，12位分辨率
   */
  void init();

  /**
   * @brief 开启蜂鸣器
   * 
   * 以当前设置的频率开始蜂鸣
   * 占空比为50%
   */
  void on();

  /**
   * @brief 停止蜂鸣
   * 
   * 将PWM占空比设置为0，停止蜂鸣器发声
   */
  void off();

  /**
   * @brief 改变蜂鸣器频率
   * 
   * @param freq 目标频率(Hz)，建议范围200-2700Hz
   *             - 200-300Hz: 低音，声音较小
   *             - 400-600Hz: 中音，适合提示音
   *             - 2700-3000Hz: 高音，声音刺耳，适合警报
   */
  void changeFreq(uint32_t freq);

  /**
   * @brief 播放指定频率的音调
   * 
   * @param freq 音调频率(Hz)
   * @param duration 持续时间(毫秒)，0表示持续播放
   */
  void playTone(uint32_t freq, uint32_t duration = 0);

  /**
   * @brief 播放提示音
   * 
   * 播放一个简短的"滴"声(2700Hz, 100ms)
   */
  void beep();

  /**
   * @brief 播放警告音
   * 
   * 播放两声"滴滴"(2700Hz)
   */
  void beepDouble();

private:
  uint8_t _channel;      // PWM通道号
  uint8_t _pin;          // 蜂鸣器引脚
  uint8_t _resolution;   // PWM分辨率(位数)
  uint32_t _defaultFreq; // 默认频率
  bool _isPlaying;       // 是否正在播放
};
